package intopo.game.impl.givetake;

/**
 * A representation of a Give-Take game. This interface is used by classes
 * derived from class <code>GiveTakePlayer</code> when calculating the
 * action to be performed at some iteration. This interface provides methods
 * to query the past actions performed by the players, the game length and
 * the score accumulated by the players.

 * @see GiveTakePlayer#give(GiveTakeHistory,int)
 * @see GiveTakePlayer#take(GiveTakeHistory,int)

 * @author <a href="mailto:plsm@det.ua.pt">Pedro Lopes da Silva Mariano</a>

 * @version 1.0
 */
interface GiveTakeHistory
{
	/**
	 * Get the action performed by the player at the given
	 * iteration. Parameter <code>index</code> should be 0 or 1. Parameter
	 * <code>iteration</code> should lay in the interval <code>0 <=
	 * iteration && iteration &lt; getNumberIterations()</code>.

	 * @see #getNumberIterations()

	 * @param iteration the iteration number
	 * @param playerIndex the player index, 0 or 1

	 * @return the action performed by the player
	 */
	GiveTakeAction getActionAtIteration (int iteration, int playerIndex);

	/**
	 * Get the action performed by the player at some iteration in the
	 * past. For example: <code>getPastAction(1, 0)</code> returns the
	 * previous action of player 0.

	 * <p> Parameter {@code iteration} should lay in the interval
	 * {@code 0 < iteration && iteration <= getNumberIterations ()}.

	 * @see #getNumberIterations()

	 * @param iteration the past iteration number
	 * @param playerIndex the player index, 0 or 1

	 * @return the action performed by the player
	 */
	GiveTakeAction getPastAction (int iteration, int playerIndex);

	/**
	 * Get the latest iteration that the specified player played action
	 * {@code action}. A value of 1 means the previous iteration, while a
	 * value of {@code getNumberIterations()} means the first iteration of
	 * the game.

	 * @param action the action to look from starting from the previous
	 * iteration
	 * @param playerIndex the player index, 0 or 1

	 * @throws NotPlayedException if the player has not yet played the
	 * specified action

	 * @return the latest iteration, a number n such that {@code 1 <= n <=
	 * getNumberIterations()}
	 */
	int getIterationPastAction (GiveTakeAction action, int playerIndex)
		throws NotPlayedException;

	/**
	 * Get the number of iterations that have elapsed since the last
	 * resource exchange action. A value of 0 means that in the last
	 * iteration a give or take action occurred.
	 */
	int getIterationsSinceLastResourceExchange ();

	/*
	 * Get the number of iterations that the specified player has the
	 * resource counting from the latest resource exchange action. If no
	 * such action has occured then if the player does not have the resource
	 * the value {@code -1} is returned, otherwise the value {@code
	 * getNumberIterations()} is returned.

	 * @param playerIndex the player index, 0 or 1

	 * @return the number of iterations that the specified player has the
	 * resource counting from the latest resource exchange action
	 *
	int getPastIterationsWithResource (int playerIndex);
	*/

	/**
	 * Get the number of iterations that have ellapsed since the beginning
	 * of the game.

	 * @return the number of iterations that have ellapsed
	 */
	int getNumberIterations ();

// 	/**
// 	 * Get the score of the specified player.

// 	 * @param playerIndex the player index, 0 or 1

// 	 * @return the player's score
// 	 */
// 	float getScore (int playerIndex);
}
